home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / FileHndlr.3 < prev    next >
Text File  |  1994-09-20  |  5KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tk_CreateFileHandler(3)Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_CreateFileHandler, Tk_DeleteFileHandler - associate  pro-
  12.      cedure callback with a file or device
  13.  
  14. SYNOPSIS
  15.      #include <tk.h>
  16.  
  17.      Tk_CreateFileHandler(_i_d, _m_a_s_k, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  18.  
  19.      Tk_DeleteFileHandler(_i_d)
  20.  
  21. ARGUMENTS
  22.      int           _i_d           (in)      Integer identifier  for
  23.                                           an  open file or device
  24.                                           (such  as  returned  by
  25.                                           open system call).
  26.  
  27.      int           _m_a_s_k         (in)      Conditions under  which
  28.                                           _p_r_o_c  should be called:
  29.                                           OR-ed  combination   of
  30.                                           TK_READABLE,
  31.                                           TK_WRITABLE,        and
  32.                                           TK_EXCEPTION.
  33.  
  34.      Tk_FileProc   *_p_r_o_c        (in)      Procedure   to   invoke
  35.                                           whenever  the  file  or
  36.                                           device indicated by  _i_d
  37.                                           meets   the  conditions
  38.                                           specified by _m_a_s_k.
  39.  
  40.      ClientData    _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary      one-word
  41.                                           value to pass to _p_r_o_c.
  42. _________________________________________________________________
  43.  
  44.  
  45. DESCRIPTION
  46.      Tk_CreateFileHandler arranges for _p_r_o_c to be invoked in  the
  47.      future  whenever I/O becomes possible on a file or an excep-
  48.      tional condition exists for the file.  The file is indicated
  49.      by _i_d, and the conditions of interest are indicated by _m_a_s_k.
  50.      For example, if _m_a_s_k  is  TK_READABLE,  then  _p_r_o_c  will  be
  51.      called  when  the file is readable.  The callback to _p_r_o_c is
  52.      made by Tk_DoOneEvent, so Tk_CreateFileHandler is only  use-
  53.      ful  in  programs that dispatch events through Tk_DoOneEvent
  54.      or through other Tk procedures that call Tk_DoOneEvent, such
  55.      as Tk_MainLoop.
  56.  
  57.      _P_r_o_c should have arguments and result that  match  the  type
  58.      Tk_FileProc:
  59.           typedef void Tk_FileProc(
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_CreateFileHandler(3)Tk Library Procedures
  71.  
  72.  
  73.  
  74.                ClientData _c_l_i_e_n_t_D_a_t_a,
  75.                int _m_a_s_k);
  76.      The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a
  77.      argument  given  to  Tcl_CreateFileHandler when the callback
  78.      was created.  Typically, _c_l_i_e_n_t_D_a_t_a points to a data  struc-
  79.      ture  containing  application-specific information about the
  80.      file.  _M_a_s_k is an  integer  mask  indicating  which  of  the
  81.      requested  conditions actually exists for the file;  it will
  82.      contain a subset  of  the  bits  in  the  _m_a_s_k  argument  to
  83.      Tcl_CreateFileHandler.
  84.  
  85.      There may exist only one handler for a given file at a given
  86.      time.   If  Tk_CreateEventHandler  is  called when a handler
  87.      already exists for _i_d, then the _m_a_s_k, _p_r_o_c,  and  _c_l_i_e_n_t_D_a_t_a
  88.      for the new call to Tk_CreateEventHandler replace the infor-
  89.      mation that was previously recorded.
  90.  
  91.      Tk_DeleteFileHandler  may  be  called  to  delete  the  file
  92.      handler  for _i_d;  if no handler exists for the file given by
  93.      _i_d then the procedure has no effect.
  94.  
  95.      The purpose of file handlers is to enable an application  to
  96.      respond to X events and other events while waiting for files
  97.      to become ready for I/O.  For this to  work  correctly,  the
  98.      application  must  use  non-blocking  I/O  operations on the
  99.      files for which handlers are declared.  Otherwise the appli-
  100.      cation  may  be  put  to  sleep if it specifies too large an
  101.      input or output buffer; while waiting for the  I/O  to  com-
  102.      plete the application won't be able to service other events.
  103.      In BSD-based UNIX systems, non-blocking I/O can be specified
  104.      for  a  file  using  the  fcntl kernel call with the FNDELAY
  105.      flag.
  106.  
  107.  
  108. KEYWORDS
  109.      callback, file, handler
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.